API Temporal JavaScript: Penanganan Tanggal dan Waktu Modern untuk Audiens Global

Objek `Date` JavaScript telah lama menjadi sumber frustrasi bagi para pengembang. Sifatnya yang dapat diubah (mutable), API yang tidak konsisten, dan dukungan zona waktu yang buruk telah menyebabkan munculnya banyak pustaka seperti Moment.js dan date-fns untuk mengisi kekosongan tersebut. Sekarang, dengan API Temporal, JavaScript menawarkan solusi modern bawaan untuk menangani tanggal dan waktu dengan kejelasan dan presisi yang lebih baik. Artikel ini memberikan gambaran komprehensif tentang API Temporal, dengan fokus pada fitur, manfaat, dan penggunaannya dalam berbagai konteks internasional.

Apa itu API Temporal?

API Temporal adalah objek global baru di JavaScript yang dirancang untuk mengatasi kekurangan objek `Date`. API ini menyediakan API yang bersih dan tidak dapat diubah (immutable) untuk bekerja dengan tanggal, waktu, zona waktu, dan sistem kalender. Yang terpenting, API ini bertujuan untuk merepresentasikan konsep tanggal dan waktu dengan cara yang lebih selaras dengan penggunaan dan ekspektasi dunia nyata, membuat internasionalisasi menjadi jauh lebih mudah.

Fitur Utama:

• Imutabilitas: Objek temporal bersifat immutable, artinya operasi seperti menambahkan hari atau bulan akan mengembalikan objek baru alih-alih memodifikasi objek asli. Ini menghilangkan sumber bug yang umum dan membuat kode lebih mudah dipahami.
• API yang Jelas: Temporal menyediakan API yang konsisten dan intuitif untuk operasi tanggal dan waktu yang umum.
• Dukungan Zona Waktu: Temporal menyertakan dukungan yang kuat untuk zona waktu, memungkinkan Anda bekerja dengan tanggal dan waktu di lokasi yang berbeda tanpa kerumitan objek `Date` yang lama. API ini menggunakan basis data zona waktu IANA, memastikan informasi yang akurat dan terkini.
• Sistem Kalender: Selain kalender Gregorian, Temporal mendukung sistem kalender alternatif, memenuhi kebutuhan beragam budaya dan wilayah.
• Presisi yang Ditingkatkan: Temporal menawarkan presisi nanodetik, mengatasi keterbatasan objek `Date` yang berbasis milidetik.

Objek Dasar Temporal

API Temporal memperkenalkan beberapa jenis objek baru. Berikut adalah beberapa yang utama:

• `Temporal.PlainDate`: Merepresentasikan tanggal (tahun, bulan, hari) tanpa zona waktu.
• `Temporal.PlainTime`: Merepresentasikan waktu (jam, menit, detik, milidetik, mikrodetik, nanodetik) tanpa tanggal atau zona waktu.
• `Temporal.PlainDateTime`: Merepresentasikan tanggal dan waktu tanpa zona waktu.
• `Temporal.ZonedDateTime`: Merepresentasikan tanggal dan waktu dengan zona waktu tertentu.
• `Temporal.Instant`: Merepresentasikan momen waktu tertentu, diukur dalam nanodetik sejak epoch Unix (1 Januari 1970 UTC).
• `Temporal.TimeZone`: Merepresentasikan zona waktu.
• `Temporal.Duration`: Merepresentasikan rentang waktu (misalnya, 2 jam, 30 menit).
• `Temporal.YearMonth`: Merepresentasikan tahun dan bulan.
• `Temporal.MonthDay`: Merepresentasikan bulan dan hari.

Bekerja dengan Tanggal

Membuat `Temporal.PlainDate`

Untuk membuat `Temporal.PlainDate`, Anda dapat menggunakan konstruktor:

            const plainDate = new Temporal.PlainDate(2024, 10, 27); // Tahun, Bulan (1-12), Hari
console.log(plainDate.toString()); // Output: 2024-10-27
            

              
                Copy
              
            
          

Anda juga dapat menggunakan metode `from`, yang menerima string dalam format ISO 8601:

            const plainDateFromString = Temporal.PlainDate.from('2024-10-27');
console.log(plainDateFromString.toString()); // Output: 2024-10-27
            

              
                Copy
              
            
          

Mendapatkan Komponen Tanggal

Anda dapat mengakses komponen tanggal individual menggunakan properti seperti `year`, `month`, dan `day`:

            console.log(plainDate.year); // Output: 2024
console.log(plainDate.month); // Output: 10
console.log(plainDate.day); // Output: 27
            

              
                Copy
              
            
          

Aritmetika Tanggal

Untuk menambah atau mengurangi hari, minggu, bulan, atau tahun, gunakan metode `plus` dan `minus`. Metode ini mengembalikan objek `Temporal.PlainDate` baru:

            const nextWeek = plainDate.plus({ days: 7 });
console.log(nextWeek.toString()); // Output: 2024-11-03

const lastMonth = plainDate.minus({ months: 1 });
console.log(lastMonth.toString()); // Output: 2024-09-27
            

              
                Copy
              
            
          

Membandingkan Tanggal

Anda dapat membandingkan tanggal menggunakan metode `compare`:

            const date1 = new Temporal.PlainDate(2024, 10, 27);
const date2 = new Temporal.PlainDate(2024, 11, 15);

console.log(Temporal.PlainDate.compare(date1, date2)); // Output: -1 (date1 lebih awal dari date2)
            

              
                Copy
              
            
          

Bekerja dengan Waktu

Membuat `Temporal.PlainTime`

Untuk membuat `Temporal.PlainTime`, gunakan konstruktor:

            const plainTime = new Temporal.PlainTime(10, 30, 0); // Jam, Menit, Detik
console.log(plainTime.toString()); // Output: 10:30:00
            

              
                Copy
              
            
          

Atau gunakan metode `from` dengan string waktu ISO 8601:

            const plainTimeFromString = Temporal.PlainTime.from('10:30:00');
console.log(plainTimeFromString.toString()); // Output: 10:30:00
            

              
                Copy
              
            
          

Mendapatkan Komponen Waktu

            console.log(plainTime.hour); // Output: 10
console.log(plainTime.minute); // Output: 30
console.log(plainTime.second); // Output: 0
            

              
                Copy
              
            
          

Aritmetika Waktu

            const later = plainTime.plus({ minutes: 15 });
console.log(later.toString()); // Output: 10:45:00
            

              
                Copy
              
            
          

Bekerja dengan Tanggal dan Waktu Bersamaan

Membuat `Temporal.PlainDateTime`

Anda dapat membuat `Temporal.PlainDateTime` secara langsung atau dengan menggabungkan `Temporal.PlainDate` dan `Temporal.PlainTime`:

            const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
console.log(plainDateTime.toString()); // Output: 2024-10-27T10:30:00

const date = new Temporal.PlainDate(2024, 10, 27);
const time = new Temporal.PlainTime(10, 30, 0);
const combinedDateTime = date.toPlainDateTime(time);
console.log(combinedDateTime.toString()); // Output: 2024-10-27T10:30:00
            

              
                Copy
              
            
          

Zona Waktu

Menangani zona waktu dengan benar sangat penting для aplikasi yang berurusan dengan pengguna di lokasi yang berbeda. API Temporal menyediakan dukungan zona waktu yang kuat melalui objek `Temporal.ZonedDateTime` dan `Temporal.TimeZone`.

Membuat `Temporal.ZonedDateTime`

Untuk membuat `Temporal.ZonedDateTime`, Anda memerlukan `Temporal.PlainDateTime` dan pengidentifikasi zona waktu. Pengidentifikasi zona waktu didasarkan pada basis data zona waktu IANA (misalnya, `America/Los_Angeles`, `Europe/London`, `Asia/Tokyo`).

            const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
const timeZone = 'America/Los_Angeles';
const zonedDateTime = plainDateTime.toZonedDateTime(timeZone);
console.log(zonedDateTime.toString()); // Output: 2024-10-27T10:30:00-07:00[America/Los_Angeles] (Offset akan bergantung pada aturan DST)

            

              
                Copy
              
            
          

Sebagai alternatif, buat `Temporal.ZonedDateTime` dari sebuah `Instant`.

            const instant = Temporal.Instant.fromEpochSeconds(1666866600); // Contoh stempel waktu
const zonedDateTimeFromInstant = instant.toZonedDateTimeISO(timeZone); // Zona waktu seperti 'America/Los_Angeles'
console.log(zonedDateTimeFromInstant.toString());
            

              
                Copy
              
            
          

Mengonversi Antar Zona Waktu

Anda dapat mengonversi `Temporal.ZonedDateTime` ke zona waktu yang berbeda menggunakan metode `withTimeZone`:

            const newTimeZone = 'Europe/London';
const zonedDateTimeInLondon = zonedDateTime.withTimeZone(newTimeZone);
console.log(zonedDateTimeInLondon.toString()); // Output: 2024-10-27T18:30:00+01:00[Europe/London]
            

              
                Copy
              
            
          

Bekerja dengan Offset Zona Waktu

Metode `getOffsetStringFor` dari objek `Temporal.TimeZone` menyediakan string offset untuk `Temporal.Instant` yang diberikan:

            const timeZoneObject = new Temporal.TimeZone(timeZone);
const offsetString = timeZoneObject.getOffsetStringFor(zonedDateTime.toInstant());
console.log(offsetString); // Output: -07:00 (Tergantung pada aturan DST)
            

              
                Copy
              
            
          

Sangat penting untuk menggunakan pengidentifikasi zona waktu IANA yang benar untuk perhitungan yang akurat. Pengidentifikasi ini dipelihara dan diperbarui secara berkala untuk mencerminkan perubahan waktu musim panas (daylight saving time) dan batas zona waktu.

Durasi

Objek `Temporal.Duration` merepresentasikan rentang waktu. Objek ini dapat digunakan untuk menambah atau mengurangi dari tanggal dan waktu.

Membuat `Temporal.Duration`

Anda dapat membuat `Temporal.Duration` menggunakan konstruktor, dengan menentukan tahun, bulan, hari, jam, menit, detik, milidetik, mikrodetik, dan nanodetik:

            const duration = new Temporal.Duration(1, 2, 3, 4, 5, 6, 7, 8, 9); // Tahun, Bulan, Hari, Jam, Menit, Detik, Milidetik, Mikrodetik, Nanodetik
console.log(duration.toString()); // Output: P1Y2M3DT4H5M6.007008009S
            

              
                Copy
              
            
          

Atau dengan menggunakan string durasi ISO 8601:

            const durationFromString = Temporal.Duration.from('P1Y2M3DT4H5M6S');
console.log(durationFromString.toString()); // Output: P1Y2M3DT4H5M6S
            

              
                Copy
              
            
          

Menambahkan Durasi ke Tanggal dan Waktu

            const plainDate = new Temporal.PlainDate(2024, 10, 27);
const duration = new Temporal.Duration(0, 0, 7); // 7 hari
const newDate = plainDate.plus(duration);
console.log(newDate.toString()); // Output: 2024-11-03
            

              
                Copy
              
            
          

Perhatikan bahwa menambahkan durasi yang melibatkan bulan atau tahun ke tanggal memerlukan pertimbangan yang cermat, karena jumlah hari dalam sebulan atau setahun dapat bervariasi.

Sistem Kalender

API Temporal mendukung sistem kalender yang berbeda selain kalender Gregorian. Ini sangat penting untuk aplikasi yang perlu menangani tanggal dalam berbagai konteks budaya. Meskipun dukungan masih berkembang, ini memberikan dasar untuk ekspansi di masa depan.

Menggunakan Kalender Alternatif

Untuk menggunakan kalender tertentu, Anda dapat menentukannya saat membuat objek Temporal:

            const hebrewDate = new Temporal.PlainDate(5785, 1, 1, { calendar: 'hebrew' });
console.log(hebrewDate.toString()); // Output spesifik mungkin bervariasi tergantung pada implementasi dan pemformatan. Memerlukan polyfill di banyak lingkungan saat tulisan ini dibuat.
            

              
                Copy
              
            
          

Penting: Dukungan untuk kalender non-Gregorian mungkin memerlukan polyfill atau dukungan browser/lingkungan tertentu. Periksa dokumentasi API Temporal dan tabel kompatibilitas browser untuk informasi terbaru.

Memformat Tanggal dan Waktu

Meskipun API Temporal berfokus pada manipulasi tanggal dan waktu, pemformatan biasanya ditangani oleh objek `Intl.DateTimeFormat`, yang merupakan bagian dari API Internasionalisasi. Objek temporal bekerja dengan lancar dengan `Intl.DateTimeFormat`.

Menggunakan `Intl.DateTimeFormat`

Berikut cara memformat `Temporal.PlainDate` menggunakan `Intl.DateTimeFormat`:

            const plainDate = new Temporal.PlainDate(2024, 10, 27);
const formatter = new Intl.DateTimeFormat('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
console.log(formatter.format(plainDate)); // Output: October 27, 2024

const formatterGerman = new Intl.DateTimeFormat('de-DE', { year: 'numeric', month: 'long', day: 'numeric' });
console.log(formatterGerman.format(plainDate)); // Output: 27. Oktober 2024
            

              
                Copy
              
            
          

Anda dapat menyesuaikan opsi format sesuai kebutuhan Anda. Argumen pertama untuk `Intl.DateTimeFormat` adalah lokal, yang menentukan bahasa dan konvensi regional yang digunakan untuk pemformatan. Menggunakan lokal yang berbeda (misalnya, 'en-US', 'de-DE', 'fr-FR', 'ja-JP') menghasilkan format output yang berbeda.

Memformat `Temporal.ZonedDateTime`

Memformat `Temporal.ZonedDateTime` serupa, tetapi Anda juga dapat menyertakan informasi zona waktu dalam output:

            const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
const timeZone = 'America/Los_Angeles';
const zonedDateTime = plainDateTime.toZonedDateTime(timeZone);

const formatter = new Intl.DateTimeFormat('en-US', { year: 'numeric', month: 'long', day: 'numeric', hour: 'numeric', minute: 'numeric', timeZoneName: 'short' });
console.log(formatter.format(zonedDateTime)); // Output: October 27, 2024, 10:30 AM PDT (Singkatan zona waktu tergantung pada aturan DST)
            

              
                Copy
              
            
          

Praktik Terbaik Internasionalisasi

Saat bekerja dengan tanggal dan waktu dalam konteks global, perhatikan praktik terbaik berikut:

• Gunakan Pengidentifikasi Zona Waktu IANA: Selalu gunakan pengidentifikasi zona waktu IANA (misalnya, `America/Los_Angeles`, `Europe/London`) untuk penanganan zona waktu yang akurat.
• Waspadai Waktu Musim Panas (Daylight Saving Time): Waktu musim panas (DST) dapat memengaruhi offset zona waktu. API Temporal secara otomatis menangani transisi DST.
• Gunakan `Intl.DateTimeFormat` untuk Pemformatan: Gunakan objek `Intl.DateTimeFormat` untuk memformat tanggal dan waktu sesuai dengan lokal pengguna.
• Pertimbangkan Sistem Kalender: Jika aplikasi Anda perlu mendukung pengguna dalam konteks budaya yang berbeda, pertimbangkan untuk menggunakan sistem kalender alternatif.
• Simpan Tanggal dan Waktu dalam UTC: Saat menyimpan tanggal dan waktu di basis data, praktik terbaiknya adalah menyimpannya dalam UTC (Coordinated Universal Time) untuk menghindari masalah zona waktu. Kemudian, konversikan ke waktu lokal untuk tujuan tampilan. Temporal menyediakan metode untuk mengonversi ke dan dari UTC.
• Uji Secara Menyeluruh: Uji aplikasi Anda dengan berbagai zona waktu, lokal, dan sistem kalender untuk memastikan aplikasi berfungsi dengan benar untuk semua pengguna.

Perbandingan API Temporal dengan Objek Date Lama

Berikut adalah tabel yang menyoroti perbedaan utama dan keuntungan API Temporal dibandingkan dengan objek `Date` yang lama:

Dukungan Browser dan Polyfill

Sebagai API yang relatif baru, dukungan browser untuk API Temporal masih terus berkembang. Periksa tabel kompatibilitas browser terbaru (misalnya, di MDN Web Docs) untuk melihat browser dan lingkungan mana yang mendukungnya secara native. Untuk browser atau lingkungan yang lebih lama tanpa dukungan native, Anda dapat menggunakan polyfill untuk menyediakan fungsionalitas API Temporal. Cari "Temporal API polyfill" di web untuk menemukan opsi yang sesuai.

Kesimpulan

API Temporal JavaScript merupakan langkah maju yang signifikan dalam menangani tanggal dan waktu di JavaScript. Sifatnya yang immutable, API yang jelas, dukungan zona waktu yang kuat, dan kemampuan sistem kalender menjadikannya alat yang ampuh bagi pengembang yang membangun aplikasi yang perlu bekerja dengan tanggal dan waktu secara akurat dan andal dalam berbagai konteks internasional. Meskipun dukungan browser masih berkembang, manfaat dari API Temporal membuatnya layak dipelajari dan diadopsi untuk proyek-proyek baru. Dengan merangkul API Temporal dan mengikuti praktik terbaik internasionalisasi, Anda dapat membuat aplikasi yang memberikan pengalaman tanggal dan waktu yang lancar dan akurat bagi pengguna di seluruh dunia.

Pembelajaran Lebih Lanjut

• Dokumentasi Resmi API Temporal
• MDN Web Docs tentang Temporal